<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

	<title>User Defined Markup</title>
	<meta title="template local_template.html">
</head>

<body>

<div id="main_title">User Defined Markup</div>
<div id="content">
<p>As most Python tutorials are not adapted for Crunchy, they do not
contain the required markup indicating to Crunchy which interactive element
to insert.  In order to make Crunchy useful with any such tutorial,
it is possible to instruct it to insert interactive elements
even where no special markup is present.</p>
<p>Similarly, sometimes the choices made by a tutorial writer,
whether by design or by accident, may not yield the desired
result by the reader using Crunchy.  This is why we made it possible
to modify the existing markup in a fairly simple fashion.</p>
<p>In the following, we will give concrete examples of both situations.</p>
<h2>No markup</h2>
<p>The most frequent case is that of no existing markup.  By this, 
we mean that a <tt>pre</tt> tag has been used with no <tt>title</tt>
attribute.  By default, Crunchy will format these as follows:</p>
<ul>
<li>If the Python code contained within a <tt>pre</tt>
starts with the interpreter prompt,
Crunchy assumes it is an interpreter session and inserts an interpreter.</li>
<li>If the Python code does not start with an interpreter prompt,
then Crunchy assumes it is just normal code that needs to be styled,
but not interacted with.</li>
</ul>
<p>This default option is noted as <b>python_tutorial</b>.  If you have
not modified Crunchy's default, you may see the result below.</p>
<p>First, a bare <tt>pre</tt> containing a simulated interactive
session.</p>
<pre>
>>> print "Hello"
Hello
>>> a = 3
>>> b = 5
>>> c = a + b
>>> print c
8
</pre>
<p>The above should have an interpreter insert by default.</p>
<p>A similar <tt>pre</tt> but this time with no interactive prompt.  
This should just style the code.
</p>
<pre>
print "Hello World!"
</pre>
<p>If you wish, you may want to select</p>
<pre title="interpreter">
>>> crunchy.no_markup = "editor"
</pre>
<p>and reload the page.  You will see that the markup in the two
top examples on this page will have changed.  You can try other values
for <tt>crunchy.no_markup</tt>.  If you enter an invalid value, Crunchy
will give you feedback, letting you know which values are allowed - these
are only "one word long", specifying a type of interactive element
to insert (but no "fine tuning" options, such as adding linenumbers).
We suggest that you revert to <tt>python_tutorial</tt> when you are
done with playing with this example, as Crunchy will remember you last
choice (saving it into a configuration file).</p>

<h2>Modifying existing markup</h2>

<p>Sometimes you would like to override existing Crunchy markup on a page,
or perhaps add options to the "no_markup" option above.  This can
be done by an advanced configuration option.  To begin, we will
give you four examples with pre-existing markup, and then show you
how to modify them.</p>
<h3>A sample Python code, using "python" as the markup.</h3>
<pre title="python">
print "Crunchy is great!"
</pre>
<h3>A sample interactive session using "interpreter linenumber=99" as the markup.</h3>
<pre title="interpreter linenumber=99">
>>> for letter in 'Crunchy':
...     print letter, '-', 
</pre>
<h3>An editor with "editor linenumber" as the markup.</h3>
<pre title="editor linenumber">
>>> for i in range(10):
...     print i, i**2
</pre>
<h3>A simple "doctest".</h3>
<pre title="doctest">
>>> double(4)
8
</pre>

<h2>The actual method to modify existing markup</h2>

<p>The first thing you need to do to be able to modify existing
markup is to instruct Crunchy as follows:</p>
<pre title="Borg">
>>> crunchy.modify_markup = True
</pre>
<p>By default, this is set to <code title="py_code">False</code>. 
Every time you change this value, Crunchy saves the new value (like it does
for any configuration option) in a configuration file.  This way, you don't
have to select your favourite option every time you restart Crunchy.</p>
<p>By itself, the above does not do anything.  To actually instruct
Crunchy to alter existing markup, we need to give it a series of rules.
Try the following:</p>
<pre title="Borg">
>>> crunchy.add_rule()
Enter a rule method to modify markup. 
The allowed values are: add_option, remove_option, replace 
Enter method: add_option
Enter option to add (e.g. linenumber): show_vlam
>>> crunchy.add_rule() 
Enter a rule method to modify markup. 
The allowed values are: add_option, remove_option, replace 
Enter method: replace
Markup value to replace: doctest
Replacement value: interpreter
</pre>
<p>After you have done this, reload the page to see the effect.</p>
<p>Note in particular how the show_vlam option will reveal the
vlam code used for any element styled by Crunchy.</p>
<p>Finally, you can view all the rules you have chosen
and delete those you don't want anymore.</p>
<pre title="Borg">
>>> crunchy.list_rules()
# method arguments 
0 add_option ['linenumber'] 
1 replace ['doctest', 'interpreter'] 
>>> crunchy.remove_rule(0) 
>>> crunchy.remove_rule(1)  # will generate an error 
</pre>
<p>As you instruct Crunchy to remove rule "0", it renumbers
the existing rules (they are stored in a Python list) so that
the old rule "1" becomes the new rule "0".</pre>

<p><a href="index.html">Back to the test index</a></p>

</div>
</body>
</html>